  Apple // Game Server

Play the classics on your Woz machine without a floppy disk!



  Program Overview

Prior to executing the java program, the apple // computer must be
connected, powered on, and expecting input (via typing in#2 at the basic
prompt.)  Once you've typed IN#2, the apple SSC firmware (or equivilant
firmware in the rom of the //gs or //c) takes over the normal keyboard
input routine and starts listening on the serial port for input in
addition to the normal keyboard input.  Therefore, whatever is connected
to the serial port can gain remote control over the apple's keyboard and
type stuff in really fast -- well, at least fast compared to how I type
anyway.  ;-)  So now the apple is listening for input, we can now start
the java program.

The first phase of the java program is contained in two script files,
init.txt and driver.txt, which contain all the necessary logic for
getting the apple ready for higher speed communication.  Very simply, a
short pre-assembled apple program (nicknamed SOS, for Serial Operating
System) is typed in one byte at a time over the serial cable and then
executed on the apple.

Note: The init phase is where the bulk of problems are experienced,
because of the possibility of misconfiguration or a damaged serial
cable.  Because of this, it is very important to check the link works
bi-directionally first using a normal communications program like
HyperTerminal (or whatever is relevant to your OS -- feel free to share
your opinions on this in the forums.)  Whatever error messages can be
thrown by the java program are described in the FAQ section.

Once the driver program has been entered in memory, it is executed by
the final line of driver.txt: "300g".  Once the driver starts, the java
program can gain more direct control over the apple to perform specific
functions.  The first thing that happens is an ackowledgement test.  The
java program sends an @ (at) character to the apple.  The Apple, if
working properly at this point, should respond with "hi".  If the test
succeeds, an entire application starts executing inside of the java
program, using the apple as the display and keyboard input, basically
turning the apple into a dumb terminal.

Main Loop: The java program prepares a virtual screen buffer in its own
memory space and then sends it over (1kb total) to the apple,
instructing the apple to store the data directly in its text screen
buffer ($400).  After the screen is sent, the java program then tells
the apple to wait for a keypress.  If the apple receives a keypress it
sends it back.  (if not, it sends back a negative response -- this is
used to verify the connection is unbroken)  If the keypress is
understood by the java program, it responds to it and then updates its
virtual screen buffer and then sends the screen back to the apple.  This
whole process loops until the user selects a game.

Once the game is selected, the java program sends the binary of the game
file over and then instructs the driver to start executing it.   After
that, the java program disconnects and exits and the apple is
(hopefully) now playing a game.


  Script Commands

The init.txt and driver.txt files are interpreted scripts that contain
all the necessary setup commands and apple program code necessary to get
the apple to communicate with the java program more directly.  These
scripts may be found in the lib/data directory.  The
ags.communications.GenericHost class is where the script interpreter
lives for now.
The init.txt script is executed first to set up the basic parameters of
the program and get the apple ready to receive the driver program code.
 If the init.txt script is successful, the driver.txt script is executed
to enter and start the driver program.

When a script is executed, it is interpreted top-down starting at the
first line.  The punctuation symbols at the beginning of each line
control the script flow and how data should be sent to the apple.

Script Key:

    * (none) The line is typed with echo-check enabled and no prompt
      response expected
    * ~ (tilde) The line is blindly typed (no echo-check enabled) and no
      prompt response expected
    * * (asterisk) The line is typed with echo-check enabled and expects
      a monitor prompt in response
    * ] (left-bracket) The line is typed with echo-check enabled and
      expects a basic prompt in response
    * " (double-quote) The line is echoed out to the apple's screen,
      implicitly expects a monitor prompt afterwards
    * ' (single-quote) The line is echoed out to the user (java) through
      stdout
    * ! (exclamation) This is a command for the java program to
      interpret, not to be typed (see java program commands below)
    * : (colon) This is a label for the java progrram, not to be typed
    * ; (semi-colon) The line is a comment and is ignored

Accepted java program commands (used with the ! symbol):

    * baud rate  Set the local machine's baud rate to the specified number
    * flow NONE|HARDWARE|XON  Set the local machine's flow control mode
    * onerror label-name  If an error is encountered, jump to the
      specified label in this script (throws the error if the label is
      not found)
    * goto label-name  Jump directly to the specified label (throws an
      error if the label is not found)
    * wait milliseconds  Pause the specified number of milliseconds
      before going on.
    * expect true|false  Enable/disable echo-check

About the "echo-check" mode: Echo-check mode is a way to verify that the
apple is receiving data.  This requires that the apple can support this.
 //c firmware does this by default, but the SSC firmware in a //e
probably does not.  (You can enable this on the //e by typing "CTRL+A 2
S" after typing IN#2 -- without the spaces).  Echo check forces the java
program to wait for data sent from the java program to echo back from
the apple before entering another character.
If the echo check fails, the java program will throw an error indicating
the apple is not communicating correctly.  This is how baud rate
detection works, because a failure of echo-checking means the baud rates
don't match up.  However, with echo-check mode disabled the baud rate
detection will not work because there will not be a communication error
until the very end once the java program has already tried to send over
and execute the driver program
back to top <#overview>


  Serial Operating System (SOS)

SOS is the apple driver program that allows the java progam to take
total control. Until SOS is instructed to execute a program, it runs its
own simple main loop:

   1. Wait for input "command" character from remote host (java program)
   2. Pick appropriate subroutine for command and execute it (if command
      was not understood, it just beeps the apple speaker)
   3. Unless the program execute command (E) was called, jump back to
      step 1.

There are only a small number of commands that are accepted:

    * @  Acknowledge request -- apple responds back with "hi"
    * A  Set target address for execution or for data download
    * B  Set data download size
    * C  Receive n bytes of data (as set by B) and store them starting
      at address specified by A -- calculates checksum as it downloads
    * D  Request calculated checksum value (apple replies back with a
      one-byte checksum value, an XOR of all received bytes from C)
    * E  Execute program at target address specified by A
    * F  Wait a little while for keypress and respond back with value.
       (>=128 means key was pressed, < 128 means no key was pressed)

That is basically it for the apple side of things.  The game selection
menu actually resides inside the java program and uses a combination of
these commands to make the apple look like it is running the program
(nice illusion, isn't it?)
back to top <#overview>
 Game Server was written by Brendan Robert
<http://brendan.robert.googlepages.com/home>, CopyLeft(c) 2006. All
Rights Reserved.  Use and redistribution of this software is subject to
the terms of the GNU Public License <http://www.gnu.org/copyleft/gpl.html>.
